\input cwebmac \parskip 0pt plus 1pt \def\RA{\char'31 } % right arrow \def\hang{\hangindent 4em\ignorespaces} \font\ninerm=cmr9 \font\ninett=cmtt9 \font\eighttt=cmtt8 \def\Pascal{Pascal} \def\cee{C} \font\quoterm=cmssq8 \font\quoteit=cmssqi8 \def\pb{\.{|...|}} \def\v{\.{\char'174}} % vertical (|) in typewriter font \def\lpile{\def\cr{\hfill\endline}\matrix} % I only use \lpile by itself \outer\def\section #1.{\penalty-50\vskip 12pt plus 3pt minus 3pt \noindent{\bf #1.}\quad\ignorespaces} \def\titlepage{T} \def\lheader{\mainfont\the\pageno\hfill\sc\runninghead\hfill} \def\rheader{\hfill\ifnum\the\pageno=1\else\sc\runninghead\hfill \mainfont\the\pageno\fi} \def\runninghead{{\tentt CWEB} USER MANUAL} \def\narrower{\medskip\bgroup\rightskip=24pt\leftskip=24pt} \def\endnarrower{\medskip\egroup} % This verbatim mode assumed that no ? appears in the text being copied. \def\verbatim{\begingroup \def\do##1{\catcode`##1=12 } \dospecials \parskip 0pt \parindent 0pt \catcode`\ =13 \catcode`\^^M=13 \tt \catcode`\?=0 \verbatimdefs \verbatimgobble} {\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} % \gdef\verbatimgobble#1^^M{}} \centerline{\titlefont A \cee\ version of {\ttitlefont WEB}} \vskip 15pt plus 3pt minus 3pt \section Introduction. This document describes a version of Don Knuth's \.{WEB} system of structured documentation, adapted to \cee\ by Silvio Levy. This version was entirely rewritten in \cee, and many changes were made to take advantage of features offered by \cee\ but non-existent in \Pascal. The bulk of this document, not counting appendixes~A--E, consists of quotes from Knuth's memo ``The \.{WEB} System of Structured Documentation;'' these quotes are clearly distinguished by their indentation, and apart from the substitution of the word ``\cee'' for ``\Pascal'' and of `\.{@c}' for `\.{@p}' all other changes to them are explicitly indicated. This also serves to indicate which commands and features are common to both versions of \.{WEB} and which are characteristic of this version (of course if you're new to \.{WEB} you don't have to worry about this). \narrower The philosophy behind \.{WEB} is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like \TeX\ for formatting, and a language like \cee\ for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a ``web'' that is made up of many interconnected pieces. To document such a program, we want to explain each individual part of the web and how it relates to its neighbors. The typographic tools provided by \TeX\ give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by \cee\ make it possible for us to specify the algorithms formally and unambiguously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. \dots Besides providing a documentation tool, \.{WEB} enhances the \cee\ language by providing \dots\ the ability to permute pieces of the program text, so that a large system can be understood entirely in terms of small modules and their local interrelationships. The \.{TANGLE} program is so named because it takes a given web and moves the modules from their web structure into the order required by \cee; the advantage of programming in \.{WEB} is that the algorithms can be expressed in ``untangled'' form, with each module explained separately. The \.{WEAVE} program is so named because it takes a given web and intertwines the \TeX\ and \cee\ portions contained in each module, then it knits the whole fabric into a structured document. (Get it? Wow.) Perhaps there is some deep connection here with the fact that the German word for ``weave'' is ``{\it web\/}'', and the corresponding Latin imperative is ``{\it texe\/}''! \endnarrower A user of this version of \.{WEB} should be fairly familiar with the \cee\ programming language. A minimal amount of acquaintance with \TeX\ is also desirable, but in fact it can be acquired as one uses \.{WEB}, since straight text can be typeset in \TeX\ with virtually no knowledge of the language. To someone familiar with \cee\ and \TeX\ the amount of effort necessary to learn the commands of \.{WEB} is small. \section The language. As mentioned above, in writing a \.{WEB} program the user keeps the \cee\ code and the documentation in the same file, called the \.{WEB} file and generally named \.{something.web}. The command `\.{weave something}' creates an output file \.{something.tex}, which can then be fed to \TeX, yielding a ``pretty printed'' version of \.{something.web} that correctly handles typographic details like page layout and the use of indentation, italics, boldface, etc., and that includes extensive cross-index information that is gathered automatically. Similarly, if you run the command \.{tangle something} you will get a \cee\ file \.{something.c}, with can then be compiled to yield executable code. \narrower Two kinds of material go into \.{WEB} files: \TeX\ text and \cee\ text. A programmer writing in \.{WEB} should be thinking both of the documentation and of the \cee\ program that he or she is creating; i.e., the programmer should be instinctively aware of the different actions that \.{WEAVE} and \.{TANGLE} will perform on the \.{WEB} file. \TeX\ text is essentially copied without change by \.{WEAVE}, and it is entirely deleted by \.{TANGLE}, since the \TeX\ text is ``pure documentation.'' \cee\ text, on the other hand, is formatted by \.{WEAVE} and it is shuffled around by \.{TANGLE}, according to rules that will become clear later. For now the important point to keep in mind is that there are two kinds of text. Writing \.{WEB} programs is something like writing \TeX\ documents, but with an additional ``\cee\ mode'' that is added to \TeX's horizontal mode, vertical mode, and math mode. A \.{WEB} file is built up from units called {\sl modules\/} that are more or less self-contained. Each module has three parts: \yskip\item{1)} A \TeX\ part, containing explanatory material about what is going on in the module. \item{2)} A definition part, containing macro definitions that serve as abbreviations for \cee\ constructions that would be less comprehensible if written out in full each time [they are turned by \.{TANGLE} into preprocessor macro definitions]. \item{3)} A \cee\ part, containing a piece of the program that \.{TANGLE} will produce. This \cee\ code should ideally be about a dozen lines long, so that it is easily comprehensible as a unit and so that its structure is readily perceived. \yskip\noindent The three parts of each module must appear in this order; i.e., the \TeX\ commentary must come first, then the definitions, and finally the \cee\ code. Any of the parts may be empty. A module begins with [either of the two] symbols `\.{@\ }' or `\.{@*}', where `\.{\ }' denotes a blank space. A module ends at the beginning of the next module (i.e., at the next `\.{@\ }' or `\.{@*}'), or at the end of the file, whichever comes first. The \.{WEB} file may also contain material that is not part of any module at all, namely the text (if any) that occurs before the first module. Such text is said to be ``in limbo''; it is ignored by \.{TANGLE} and copied essentially verbatim by \.{WEAVE}, so its function is to provide any additional formatting instructions that may be desired in the \TeX\ output. Indeed, it is customary to begin a \.{WEB} file with \TeX\ code in limbo that loads special fonts, defines special macros, changes the page sizes, and/or produces a title page. Modules are numbered consecutively, starting with 1; these numbers appear at the beginning of each module of the \TeX\ documentation, and they appear as bracketed comments at the beginning of the code generated by that module in the \cee\ program. Fortunately, you never mention these numbers yourself when you are writing in \.{WEB}. You just say `\.{@\ }' or `\.{@*}' at the beginning of each new module, and the numbers are supplied automatically by \.{WEAVE} and \.{TANGLE}. As far as you are concerned, a module has a name instead of a number; such a name is specified by writing `\.{@<}' followed by \TeX\ text followed by `\.{@>}'. When \.{WEAVE} outputs a module name, it replaces the `\.{@<}' and `\.{@>}' by angle brackets and inserts the module number in small type. Thus, when you read the output of \.{WEAVE} it is easy to locate any module that is referred to in another module. For expository purposes, a module name should be a good description of the contents of that module, i.e., it should stand for the abstraction represented by the module; then the module can be ``plugged into'' one or more other modules so that the unimportant details of its inner workings are suppressed. A module name therefore ought to be long enough to convey the necessary meaning. Unfortunately, however, it is laborious to type such long names over and over again, and it is also difficult to specify a long name twice in exactly the same way so that \.{WEAVE} and \.{TANGLE} will be able to match the names to the modules. Therefore a module name can be abbreviated after its first appearance in the \.{WEB} file, by typing `\.{@<$\alpha$...@>}', where $\alpha$ is any string that is a prefix of exactly one module name that appears in the file. For example, `\.{@}' can be abbreviated to `\.{@}' if no other module name begins with the five letters `\.{Clear}'. Module names must otherwise match character for character, except that consecutive blank spaces and/or tab marks are treated as equivalent to single spaces, and such spaces are deleted at the beginning and end of the name. Thus, `\.{@< Clear { }the arrays @>}' will also match the name in the previous example. We have said that a module begins with `\.{@\ }' or `\.{@*}', but we didn't say how it gets divided up into a \TeX\ part, a definition part, and a \cee\ part. The definition part begins with the first appearance of `\.{@d}' or `\.{@f}' in the module, and the \cee\ part begins with the first appearance of `\.{@c}' or `\.{@<}'. The latter option `\.{@<}' stands for the beginning of a module name, which is the name of the module itself. An equals sign (\.=) must follow the `\.{@>}' at the end of this module name; you are saying, in effect, that the module name stands for the \cee\ text that follows, so you say `$\langle\,$module name$\,\rangle=\null$\cee\ text'. Alternatively, if the \cee\ part begins with `\.{@c}' instead of a module name, the current module is said to be {\sl unnamed}. Note that module names cannot appear in the definition part of a module, because the first `\.{@<}' in a module signals the beginning of its \cee\ part. Any number of module names might appear in the \cee\ part, however, once it has started. The general idea of \.{TANGLE} is to make a \cee\ program out of these modules in the following way: First all [the macro definitions indicated by `\.{@d}' are turned into \cee\ preprocessor macro definitions and copied down. Then] the \cee\ parts of unnamed modules are copied down [with comments removed], in order; this constitutes the initial approximation $T_0$ to the text of the program. (There should be at least one unnamed module, otherwise there will be no program.) Then all module names that appear in the initial text $T_0$ are replaced by the \cee\ parts of the corresponding modules, and this substitution process continues until no module names remain. \dots If the same name has been given to more than one module, the \cee\ text for that name is obtained by putting together all of the \cee\ parts in the corresponding modules. This feature is useful, for example, in a module named `Global variables in the outer block', since one can then declare global variables in whatever modules those variables are introduced. When several modules have the same name, \.{WEAVE} assigns the first module number as the number corresponding to that name, and it inserts a note at the bottom of that module telling the reader to `See also sections so-and-so'; this footnote gives the numbers of all the other modules having the same name as the present one. The \cee\ text corresponding to a module is usually formatted by \.{WEAVE} so that the output has an equivalence sign in place of the equals sign in the \.{WEB} file; i.e., the output says `$\langle\,$module name$\,\rangle\equiv\null$\cee\ text'. However, in the case of the second and subsequent appearances of a module with the same name, this `$\equiv$' sign is replaced by `$\mathrel+\equiv$', as an indication that the \cee\ text that follows is being appended to the \cee\ text of another module. \endnarrower As \.{TANGLE} starts and leaves modules, it writes down preprocessor \.{\#line} commands, for the benefit of the compiler. This means that when the compiler gives you error messages, or when you debug your program, the messages refer to line number in the \.{WEB} file, and not in the \cee\ file. In most cases you can even forget about the \cee\ file altogether. \narrower The general idea of \.{WEAVE} is to make a \.{TEX} file from the \.{WEB} file in the following way: The first line of the \.{TEX} file [tells \TeX\ to input a file with] macros that define \.{WEB}'s documentation conventions. The next lines of the file will be copied from whatever \TeX\ text is in limbo before the first module. Then comes the output for each module in turn, possibly interspersed with end-of-page marks. Finally, \.{WEAVE} will generate a cross-reference index that lists each module number in which each \cee\ identifier appears, and it will also generate an alphabetized list of the module names, as well as a table of contents that shows the page and module numbers for each ``starred'' module. What is a ``starred'' module, you ask? A module that begins with `\.{@*}' instead of `\.{@\ }' is slightly special in that it denotes a new major group of modules. The `\.{@*}' should be followed by the title of this group, followed by a period. Such modules will always start on a new page in the \TeX\ output, and the group title will appear as a running headline on all subsequent pages until the next starred module. The title will also appear in the table of contents, and in boldface type at the beginning of its module. Caution: Do not use \TeX\ control sequences in such titles, unless you know that the \.{webmac} macros will do the right thing with them. The reason is that these titles are converted to uppercase when they appear as running heads, and they are converted to boldface when they appear at the beginning of their modules, and they are also written out to a table-of-contents file used for temporary storage while \TeX\ is working; whatever control sequences you use must be meaningful in all three of these modes. The \TeX\ output produced by \.{WEAVE} for each module consists of the following: First comes the module number (e.g., `\.{\\M123.}' at the beginning of module 123, except that `\.{\\N}' appears in place of `\.{\\M}' at the beginning of a starred module). Then comes the \TeX\ part of the module, copied almost verbatim except as noted below. Then comes the definition part and the \cee\ part, formatted so that there will be a little extra space between them if both are nonempty. The definition and \cee\ parts are obtained by inserting a bunch of funny looking \TeX\ macros into the \cee\ program; these macros handle typographic details about fonts and proper math spacing, as well as line breaks and indentation. When you are typing \TeX\ text, you will probably want to make frequent reference to variables and other quantities in your \cee\ code, and you will want those variables to have the same typographic treatment when they appear in your text as when they appear in your program. Therefore the \.{WEB} language allows you to get the effect of \cee\ editing within \TeX\ text, if you place `\.|' marks before and after the \cee\ material. For example, suppose you want to say something like this: $$\hbox{If \\{pa} is declared as \&{int} ${*}\\{pa}$, the assignment $\\{pa}={\amp}\|a[\O{0}]$ sets \\{pa} to point to the zeroth element of \|a.}$$ The \TeX\ text would look like this in your \.{WEB} file: $$\lpile{\.{If |pa| is declared as |int *pa|, the}\cr \.{assignment |pa=\&a[0]| sets |pa| to point to the zeroth element of |a|.}\cr}$$ And \.{WEAVE} translates this into something you are glad you didn't have to type: $$\lpile{\.{If \\\\\{pa\} is declared as \\\&\{int\} \$\{*\}\\\\\{pa\}\$, the}\cr \.{assignment \$\\\\\{pa\}=\{\\amp\}\\|a[\\O\{0\}]\$ sets \\\\\{pa\} to point to the zeroth element of \\|a.}\cr}$$ Incidentally, the cross-reference index that \.{WEAVE} would make, in the presence of a comment like this, would include the current module number as one of the index entries for \\{pa}, even though \\{pa} might not appear in the \cee\ part of this module. Thus, the index covers references to identifiers in the explanatory comments as well as in the program itself; you will soon learn to appreciate this feature. However, the identifiers \&{int} and \|a\ would not be indexed, because \.{WEAVE} does not make index entries for reserved words or single-letter identifiers. Such identifiers are felt to be so ubiquitous that it would be pointless to mention every place where they occur. \dots Although a module begins with \TeX\ text and ends with \cee\ text, we have noted that the dividing line isn't sharp, since \cee\ text can be included in \TeX\ text if it is enclosed in `\pb'. Conversely, \TeX\ text also appears frequently within \cee\ text, because everything in comments (i.e., between \.{/*} and right \.{*/}) is treated as \TeX\ text. Furthermore, a module name consists of \TeX\ text; thus, a \.{WEB} file typically involves constructions like `\.{if} \.{(x==0)} \.{@}' where we go back and forth between \cee\ and \TeX\ conventions in a natural way. \endnarrower \section Macros. A \.{@d} followed by $$`\\{identifier}\.{ }\hbox{\cee\ text'}\qquad\hbox{or}\qquad \\{identifier}\.(\\{par1},\dots,\\{parn}\.)\.{ }\hbox{\cee\ text'},$$ where there is no blank between the \\{identifier} and the parentheses in the second case, is transformed by \.{TANGLE} into a preprocessor command, starting with \.{\#define}, which is printed at the top of the file. If for any reason you need a \.{\#define} command at a specific spot in your \cee\ file, you can treat it as \cee\ code, instead of as a \.{WEB} macro. A `\.{@d}' macro definition can go on for several lines, and the newlines don't have to be protected by backslashes, since \.{TANGLE} itself inserts the backslashes. \section Strings and constants. If you want a string, delimited by pairs of \.' or \.", to appear in the \cee\ file, you can type it exactly so in the \.{WEB} file, except that the character `\.@' should be typed `\.{@@}' (it becomes a control code, the only one that can appear in strings; see below). Newlines should be protected by backslashes. In particular, the string `\.{'A'}' in the \.{WEB} file will be copied by \.{TANGLE} into the \cee\ file, and will be interpreted by the \cee\ compiler as the machine's code for `\.A'. \.{WEB} offers a way to uniformize the value of character constants, so that readily portable programs can be easily written (\.{WEB} itself uses this facility): if you write `\.{@'A'}' in the \.{WEB} file, \.{TANGLE} will translate this into the ASCII code for `\.A', so the value of this constant does not depend on the character set. This works for all the visible characters of the ASCII character set codes $40_8$ to $176_8$ (i.e., octal), as well as the standard \cee\ escape sequences \.{\\n}, \.{\\t}, \.{\\b}, \.{\\r} and \.{\\f}. Speaking of octal constants, \TeX\ and \cee\ have (unfortunately) incompatible ways to refer to octal and hex constants. In \TeX\ you make a constant octal or hexadecimal by prepending \.' or \.", respectively, to it; in \cee\ the constant should be preceded by \.0 or \.{0x}. In \.{WEB} it seems reasonable to let each convention hold in its respective realm; so in \cee\ text you get $40_8$ by typing `\.{040}', which \.{TANGLE} faithfully copies into the \cee\ file (for the compiler's benefit) and which \.{WEAVE} prints as $\O{\~40}$ (for the benefit of \TeX\ users). For consistency, then, you should type `\.{|040|}' in the \TeX\ part of the module. (I'm not entirely sure that this is what \.{WEB} should do; suggestions are welcome.) \section Control codes. A \.{WEB} {\sl control code\/} is a two-character combination of which the first is `\.@'. We've already seen the meaning of several control codes; here is a complete list of all of them. \narrower The letters $L$, $T$, $C$, $M$, $\\{Co}$, and/or $S$ following each code indicate whether or not that code is allowable in limbo, in \TeX\ text, in \cee\ text, in module names, in comments, and/or in strings. A bar over such a letter means that the control code terminates the present part of the \.{WEB} file; for example, $\overline L$ means that this control code ends the limbo material before the first module. \gdef\@#1[#2] {\yskip\hangindent 2em\noindent\.{@#1\unskip \spacefactor1000{ }}$[#2]$\quad} \def\oP{\overline C} \def\oT{\overline T} \@@ [\\{Co},L,M,C,S,T] A double \.@ denotes the single character `\.@'. This is the only control code that is legal in limbo, in comments, and in strings. \@\ [\overline L,\oP,\oT] This denotes the beginning of a new (unstarred) module. A tab mark or end-of-line (carriage return) is equivalent to a space when it follows an \.@ sign. \@* [\overline L,\oP,\oT] This denotes the beginning of a new starred module, i.e., a module that begins a new major group. The title of the new group should appear after the \.{@*}, followed by a period. As explained above, \TeX\ control sequences should be avoided in such titles unless they are quite simple. When \.{WEAVE} and \.{TANGLE} read a \.{@*}, they print an asterisk followed by the current module number, so that the user can see some indication of progress. The very first module should be starred. \@d [\oP,\oT] Macro definitions begin with \.{@d} (or \.{@D}), followed by [an identifier and \cee\ text as explained earlier]. \@f [\oP,\oT] Format definitions begin with \.{@f} (or \.{@F}); they cause \.{WEAVE} to treat identifiers in a special way when they appear in \cee\ text. [The general form of a format definition is `\.{@f} \|l \|r', followed by an optional comment enclosed between \.{/*} and \.{*/}, where \|l and \|r are identifiers;] \.{WEAVE} will subsequently treat identifier \|l as it currently treats \|r. This feature allows a \.{WEB} programmer to invent new reserved words and/or to unreserve some of \cee's reserved identifiers. [However, the need to do this should arise very seldom, since \.{WEAVE} knows that identifiers being defined with a \&{typedef} should become reserved words.] The definition part of each module consists of any number of macro definitions (beginning with \.{@d}) and format definitions (beginning with \.{@f}), intermixed in any order. \@c [\oP,\oT] The \cee\ part of an unnamed module begins with \.{@c} (or \.{@C}). This causes \.{TANGLE} to append the following \cee\ code to the initial program text $T_0$ as explained above. The \.{WEAVE} processor does not cause a `\.{@c}' to appear explicitly in the \TeX\ output, so if you are creating a \.{WEB} file based on a \TeX-printed \.{WEB} documentation you have to remember to insert \.{@c} in the appropriate places of the unnamed modules. Because of the rules by which every module is broken into three parts, the control codes `\.{@d}', `\.{@f}', and `\.{@c}' are not allowed to occur once the \cee\ part of a module has begun. \@< [C,\oT] A module name begins with \.{@<} followed by \TeX\ text followed by \.{@>}; the \TeX\ text should not contain any \.{WEB} control sequences except \.{@@}, unless these control sequences appear in \cee\ text that is delimited by \pb. The module name may be abbreviated, after its first appearance in a \.{WEB} file, by giving any unique prefix followed by \.{...}, where the three dots immediately precede the closing \.{@>}. Module names may not appear in \cee\ text that is enclosed in \pb, nor may they appear in the definition part of a module (since the appearance of a module name ends the definition part and begins the \cee\ part). \dots \@\& [C] The \.{@\&} operation causes whatever is on its left to be adjacent to whatever is on its right, in the \cee\ output. No spaces or line breaks will separate these two items. \dots \@\^ [C,T] The ``control text'' that follows, up to the next `\.{@>}', will be entered into the index together with the identifiers of the \cee\ program; this text will appear in roman type. For example, to put the phrase ``system dependencies'' into the index, type `\.{@\^system dependencies@>}' in each module that you want to index as system dependent. A control text \dots\ must end on the same line of the \.{WEB} file as it began. Furthermore, no \.{WEB} control sequences are allowed in a control text, not even \.{@@}. (If you need an \.{@} sign you can get around this restriction by typing `\.{\\AT!}'.) \@. [C,T] The ``control text'' that follows will be entered into the index in \.{typewriter} \.{type}; see the rules for `\.{@\^}', which is analogous. \@: [C,T] The ``control text'' that follows will be entered into the index in a format controlled by the \TeX\ macro `\.{\\9}', which the user should define as desired; see the rules for `\.{@\^}', which is analogous. \@t [C] The ``control text'' that follows, up to the next `\.{@>}', will be put into a \TeX\ \.{\\hbox} and formatted along with the neighboring \cee\ program. This text is ignored by \.{TANGLE}, but it can be used for various purposes within \.{WEAVE}. For example, you can make comments that mix \cee\ and classical mathematics, as in `$\\{size}<2^{15}$', by typing `\.{|size < @t\$2\^\{15\}\$@>|}'. A control text must end on the same line of the \.{WEB} file as it began, and it may not contain any \.{WEB} control codes. \@= [C] The ``control text'' that follows, up to the next `\.{@>}', will be passed verbatim to the \cee\ program. \@! [C,T] The module number in an index entry will be underlined if `\.{@!}' immediately precedes the identifier or control text being indexed. This convention is used to distinguish the modules where an identifier is defined, or where it is explained in some special way, from the modules where it is used. A~reserved word or an identifier of length one will not be indexed except for underlined entries. An `\.{@!}' is implicitly inserted by \.{WEAVE} [when an identified is being defined or declared in \cee\ code; for example, the definition \&{int} \\{array}[\\{max\_dim}], \\{count}${}=\\{old\_count};$ makes the names \\{array} and \\{count} get an underlined entry in the index. Statement tags, function definitions like $\\{main}(\\{argc},\39\\{argv})$ and \&{typedef} definitions also imply underlining.] \endnarrower \@' [C] This control code replaces the next character or escape sequence by its ASCII value. \narrower \@, [C] This control code inserts a thin space in \.{WEAVE}'s output; it is ignored by \.{TANGLE}. Sometimes you need this extra space if you are using macros in an unusual way, e.g., if two identifiers are adjacent. \@/ [C] This control code causes a line break to occur within a \cee\ program formatted by \.{WEAVE}; it is ignored by \.{TANGLE}. Line breaks are chosen automatically by \TeX\ according to a scheme that works 99\%\ of the time, but sometimes you will prefer to force a line break so that the program is segmented according to logical rather than visual criteria. \dots \@| [C] This control code specifies an optional line break in the midst of an expression. For example, if you have \dots\ a long expression on the right-hand side of an assignment statement, you can use `\.{@|}' to specify breakpoints more logical than the ones that \TeX\ might choose on visual grounds. \@\# [C] This control code forces a line break, like \.{@/} does, and it also causes a little extra white space to appear between the lines at this break. You might use it, for example, \dots\ between groups of macro definitions that are logically separate but within the same module. [\.{WEB} automatically inserts this extra space between functions, between external declarations and functions, and between declarations and statements within a function.] \@+ [C] This control code cancels a line break that might otherwise be inserted by \.{WEAVE}, e.g., before the word `\&{else}', if you want to put a short [if--else] construction on a single line. It is ignored by \.{TANGLE}. \@; [C] This control code is treated like a semicolon, for formatting purposes, except that it is invisible. You can use it, for example, after a module name when the \cee\ text represented by that module name ends with a semicolon. \yskip\noindent The last six control codes (namely `\.{@,}', `\.{@/}', `\.{@|}', `\.{@\#}', `\.{@+}', and `\.{@;}') have no effect on the \cee\ program output by \.{TANGLE}; they merely help to improve the readability of the \TeX-formatted \cee\ that is output by \.{WEAVE}, in unusual circumstances. \.{WEAVE}'s built-in formatting method is fairly good [when dealing with syntactically correct \cee\ text], but it is incapable of handling all possible cases, because it must deal with fragments of text involving macros and module names; these fragments do not necessarily obey \cee's syntax. Although \.{WEB} allows you to override the automatic formatting, your best strategy is not to worry about such things until you have seen what \.{WEAVE} produces automatically, since you will probably need to make only a few corrections when you are touching up your documentation. \endnarrower Actually you may not like the way \.{WEAVE} handles certain situations, for examples, the fact that statements aren't always separated by newlines. In that case you can customize \.{WEAVE} by changing its grammar. In future releases you will be able to do so at run time, but for now you have to change the source code. This is not hard; you can find a list of grammar rules in the \.{WEAVE} source listing or in the file \.{prod.web}. You can also compile \.{WEAVE} with the \.{-DDEBUG} option on the command line, and see how \.{WEAVE} is parsing your C code by preceding it with the line `\.{@ @c @2}' (the control sequence `\.{@2}' turns on the ``peeping'' mode, and `\.{@0}' turns it off). For example, if you run \.{WEAVE} on the file \medskip \begingroup \verbatim @ @c @2 main (argc,argv) char **argv; for (;argc>0;argc++) printf("%s\n",argv[argc]); ?endgroup \endgroup \medskip\noindent you get the following gibberish on your screen: \medskip \begingroup \verbatim [...] 4:*exp ( +exp+ )... 27:*exp +exp+ int... 5:*+exp+ int +unorbinop+... [...] 31:*+fn_decl+ +stmt- -ignore_scrap- 20:*+function- -ignore_scrap- 56:*+function- [...] ?endgroup \endgroup \medskip The first line says that rule 4 has just been applied, and \.{WEAVE} currently has in its memory a sequence of chunks of C code (called ``scraps'') that are of type \\{exp} (for expression), open-parenthesis, \\{exp} again, close-parenthesis. Then rule 27 is applied, and the sequence $(\,exp\,)$ becomes an \\{exp} and so on. In the end the whole C text has become one big scrap of type \\{function}. Sometimes things don't work as smoothly, and you get a bunch of lines lumped together. This means that \.{WEAVE} could not digest something in your C code. For instance, if you had written \.{@} instead of \.{char **argv;} in the program above \.{WEAVE} would have been completely mystified, since it thinks that module names are just \\{exp}s. In this case you would have to help \.{WEAVE} by writing \begingroup \verbatim main (argc,argv)@/ @@;@/ ?endgroup \endgroup \narrower \@{x @y @z}[\\{change\_file}] \.{WEAVE} and \.{TANGLE} are designed to work with two input files, called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains data that overrides selected portions of \\{web\_file}. The resulting merged text is actually what has been called the \.{WEB} file elsewhere in this report. \hangindent 2em\hskip 2em Here's how it works: The change file consists of zero or more ``changes,'' where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$% new lines$\rangle$\.{@z}'. The special control codes \.{@x}, \.{@y}, \.{@z}, which are allowed only in change files, must appear at the beginning of a line; the remainder of such a line is ignored. The $\langle$old lines$\rangle$ represent material that exactly matches consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$ represent zero or more lines that are supposed to replace the old. Whenever the first ``old line'' of a change is found to match a line in the \\{web\_file}, all the other lines in that change must match too. \hangindent 2em\hskip 2em Between changes, before the first change, and after the last change, the change file can have any number of lines that do not begin with `\.{@x}', `\.{@y}', or~`\.{@z}'. Such lines are bypassed and not used for matching purposes. \hangindent 2em\hskip 2em This dual-input feature is useful when working with a master \.{WEB} file that has been received from elsewhere (e.g., \.{TANGLE.WEB} or \.{WEAVE.WEB} or \.{TEX.WEB}), when changes are desirable to customize the program for your local computer system. You will be able to debug your system-dependent changes without clobbering the master web file; and once your changes are working, you will be able to incorporate them readily into new releases of the master web file that you might receive from time to time. \endnarrower \@i [\\{web\_file}] Furthermore the \\{web\_file} itself can be a combination of several files. When \.{WEAVE} or \.{TANGLE} are reading a file and encounter the control code \.{@i} at the beginning of a line, they interrupt their reading and start reading the file named after the \.{@i}, much as the \cee\ preprocessor does when it encounters an \.{\#include} line. After the included file is done, they go back to the next line of the original file. The file name following \.{@i} can be surrounded by \." or not; it should be made up of visible ASCII characters only, not including \.". Include files can nest. \narrower \section Additional features and caveats. 1. \dots\ In certain installations of \.{WEB} that {\def\\#1#2{`{\tentex\char'#1#2}'}% have an extended character set, the characters [\\13, \\01, \\31, \\32, \\34, \\35, \\36, \\37, and \\04} can be used as abbreviations for `\.{++}', `\.{--}', `\.{->}', `\.{!=}', `\.{<=}', `\.{>=}', `\.{==}', `\.{\v\v}', `\.{\&\&}', respectively.] However, the latter abbreviations are not used in the standard versions of \.{WEAVE.WEB} and \.{TANGLE.WEB} that are distributed to people who are installing \.{WEB} on other computers, and the programs are designed to produce only standard ASCII characters as output if the input consists entirely of ASCII characters. 2. If you have an extended character set, all of the characters listed in Appendix C of {\sl The \TeX book\/} can be used in strings. But you should stick to standard ASCII characters if you want to write programs that will be useful to all the poor souls out there who don't have extended character sets. 3. The \TeX\ file output by \.{WEAVE} is broken into lines having at most 80 characters each. The algorithm that does this line breaking is unaware of \TeX's convention about comments following `\.\%' signs on a line. When \TeX\ text is being copied, the existing line breaks are copied as well, so there is no problem with `\.\%' signs unless the original \.{WEB} file contains a line more than eighty characters long or a line with \cee\ text in \pb\ that expands to more than eighty characters long. Such lines should not have `\.\%' signs. 4. \cee\ text is translated by a ``bottom up'' procedure that identifies each token as a ``part of speech'' and combines parts of speech into larger and larger phrases as much as possible according to a special grammar that is explained in the documentation of \.{WEAVE}. It is easy to learn the translation scheme for simple constructions like single identifiers and short expressions, just by looking at a few examples of what \.{WEAVE} does, but the general mechanism is somewhat complex because it must handle much more than \cee\ itself. Furthermore the output contains embedded codes that cause \TeX\ to indent and break lines as necessary, depending on the fonts used and the desired page width. For best results it is wise [not to] enclose long \cee\ texts in \pb, since the indentation and line breaking codes are omitted when the \pb\ text is translated from \cee\ to \TeX. Stick to simple expressions or statements. [If a C preprocessor command is enclosed in \pb, the \.\# that introduces it must be at the beginning of a line, or \.{WEAVE} won't print it correctly.] 5. Comments and module names are not permitted in \pb\ text. After a `\.|' signals the change from \TeX\ text to \cee\ text, the next `\.|' that is not part of a string or control text ends the \cee\ text. 6. A comment must have properly nested occurrences of left and right braces, otherwise \.{WEAVE} [will try to balance the braces to keep \TeX\ from fouling up too much]. 8. The \.{@f} feature allows you to define one identifier to act like another, and these format definitions are carried out sequentially \dots\ However, a given identifier has only one printed format throughout the entire document (and this format will even be used before the \.{@f} that defines it). The reason is that \.{WEAVE} operates in two passes; it processes \.{@f}'s and cross-references on the first pass and does the output on the second. 10. Sometimes it is desirable to insert spacing into \cee\ code that is more general than the thin space provided by `\.{@,}'. The \.{@t} feature can be used for this purpose; e.g., `\.{@t\\hskip 1in@>}' will leave one inch of blank space. Furthermore, `\.{@t\\4@>}' can be used to backspace by one unit of indentation, since the control sequence \.{\\4} is defined in \.{webmac} to be such a backspace. (This control sequence is used, for example, at the beginning of lines that contain labeled statements, so that the label will stick out a little at the left.) \endnarrower \section Appendices. The basic ideas of \.{WEB} can be understood most easily by looking at examples of ``real'' programs. Appendix~A shows the \.{WEB} input that generated modules 19--20 of the \.{COMMON} file, which contains routines common to \.{WEAVE} and \.{TANGLE}. Appendix~B shows the corresponding \TeX\ code output by \.{WEAVE}, and Appendix~C shows how the output of \.{WEAVE} looks when printed out. Appendix~D shows the corresponding \cee\ code output by \.{TANGLE}, Appendix E is the file that sets \TeX\ up to accept the output of \.{WEAVE}, Appendix~F discusses how to use some of its macros to vary the output formats. The reader should first compare Appendix~A to Appendix~D; then the same material should be compared to Appendices~B and~C. \vfil\eject \def\runninghead{APPENDIX A --- {\tentt WEB} FILE FORMAT} \section Appendix A. The following is an excerpt of the file \.{COMMON.WEB}, which contains routines shared by \.{WEAVE} and \.{TANGLE}. Note that some of the lines are indented to show the program structure. The indentation is ignored by \.{WEAVE} and \.{TANGLE}, but users find that \.{WEB} files are quite readable if they have some such indentation. \vskip 6pt \begingroup \def\tt{\eighttt} \baselineskip9pt \verbatim @ The following procedure is used to see if the next change entry should go into effect; it is called only when |changing| is 0. The idea is to test whether or not the current contents of |buffer| matches the current contents of |change_buffer|. If not, there's nothing more to do; but if so, a change is called for: All of the text down to the \.{@@y} is supposed to match. An error message is issued if any discrepancy is found. Then the procedure prepares to read the next line from |change_file|. @= check_change() /* switches to |change_file| if the buffers match */ int n=0; /* the number of discrepancies found */ if (lines_dont_match) return; while (1) { changing=1; print_where=1; change_line++; if (!input_ln(change_file)) { err_print("! Change file ended before @@y"); @.Change file ended...@> change_limit=0; changing=0; print_where=1; return; } @; @;@/ @;@/ changing=0; print_where=1; cur_line++; while (!input_ln(cur_file)) { /* pop the stack or quit */ if (include_depth==0) { err_print("! WEB file ended during a change"); @.WEB file ended...@> input_has_ended=1; return; } include_depth--; print_where=1; cur_line++; } if (lines_dont_match) n++; @ @= if (limit>buffer+1 && buffer[0]==@'@@') { @; if (buffer[1]==@'x' || buffer[1]==@'z') { loc=buffer+2; err_print("! Where is the matching @@y?"); @.Where is the match...@> } else if (buffer[1]==@'y') { if (n>0) { loc=buffer+2; err_print("! Hmm... some of the preceding lines failed to match"); @.Hmm... some of the preceding...@> } return; ?endgroup \endgroup \vfill\eject \def\runninghead{APPENDIX B --- TRANSLATION BY {\tentt WEAVE}} \section Appendix B. This excerpt from \.{COMMON.TEX} corresponds to Appendix A. \vskip6pt \begingroup \def\tt{\eighttt} \baselineskip9pt \verbatim \M19. The following procedure is used to see if the next change entry should go into effect; it is called only when \\{changing} is 0. The idea is to test whether or not the current contents of \\{buffer} matches the current contents of \\{change\_buffer}. If not, there's nothing more to do; but if so, a change is called for: All of the text down to the \.{@y} is supposed to match. An error message is issued if any discrepancy is found. Then the procedure prepares to read the next line from \\{change\_file}. \Y\P\4\X6:Functions\X${}+\S{}$\6 $\\{check\_change}(\,)$\5 \C{ switches to \\{change\_file} if the buffers match }\6 $\{$\1\6 \&{int} \|n$=\O{0};$\5 \C{ the number of discrepancies found }\7 \&{if} (\\{lines\_dont\_match})\1\5 \&{return};\2\6 \&{while} $(\O{1})$\5 $\{$\1\6 $\\{changing}=\O{1};$\5 $\\{print\_where}=\O{1};$\5 $\\{change\_line}\PP;$\6 \&{if} $(\R\\{input\_ln}(\\{change\_file}))$\5 $\{$\1\6 $\\{err\_print}(\.{"!\ Change\ file\ ended\ before\ @y"});$\5 $\\{change\_limit}=\O{0};$\5 $\\{changing}=\O{0};$\5 $\\{print\_where}=\O{1};$\5 \&{return};\6 \4$\}$\2\6 \X16:Check for erroneous \.{@i}\X;\5 \X20:If the current line starts with \.{@y}, report any discrepancies and % \&{return}\X;\6 \X18:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change\_limit}% \X;\6 $\\{changing}=\O{0};$\5 $\\{print\_where}=\O{1};$\5 $\\{cur\_line}\PP;$\6 \&{while} $(\R\\{input\_ln}(\\{cur\_file}))$\5 $\{$\5 \C{ pop the stack or quit }\1\6 \&{if} $(\\{include\_depth}\S\O{0})$\5 $\{$\1\6 $\\{err\_print}(\.{"!\ WEB\ file\ ended\ during\ a\ change"});$\5 $\\{input\_has\_ended}=\O{1};$\5 \&{return};\6 \4$\}$\2\6 $\\{include\_depth}\MM;$\5 $\\{print\_where}=\O{1};$\5 $\\{cur\_line}\PP;$\6 \4$\}$\2\6 \&{if} (\\{lines\_dont\_match})\1\5 $\|n\PP;$\2\6 \4$\}$\2\6 \4$\}$\2\par \M20. \P\X20:If the current line starts with \.{@y}, report any discrepancies and \&{return}\X${}\S{}$\6 \&{if} $(\\{limit}>\\{buffer}+\O{1}\W\\{buffer}[\O{0}]\S\.{@'@'})$\5 $\{$\1\6 \X15:Lowercasify $\\{buffer}[\O{1}]$\X;\6 \&{if} $(\\{buffer}[\O{1}]\S\.{@'x'}\V\\{buffer}[\O{1}]\S\.{@'z'})$\5 $\{$\1\6 $\\{loc}=\\{buffer}+\O{2};$\5 $\\{err\_print}(\.{"!\ Where\ is\ the\ matching\ @y?"});$\6 \4$\}$\2\5 \&{else} \1\&{if} $(\\{buffer}[\O{1}]\S\.{@'y'})$\5 $\{$\1\6 \&{if} $(\|n>\O{0})$\5 $\{$\1\6 $\\{loc}=\\{buffer}+\O{2};$\5 $\\{err\_print}(\.{"!\ Hmm...\ some\ of\ the\ preceding\ lines\ failed\ to\ match"});$\6 \4$\}$\2\6 \&{return};\6 \4$\}$\2\2\6 \4$\}$\2\par \U section~19.\fi ?endgroup \endgroup \vfil\eject \def\runninghead{APPENDIX C --- FINAL DOCUMENT} \section Appendix C. Here's what Appendix~B looks like when typeset. \M19. The following procedure is used to see if the next change entry should go into effect; it is called only when \\{changing} is 0. The idea is to test whether or not the current contents of \\{buffer} matches the current contents of \\{change\_buffer}. If not, there's nothing more to do; but if so, a change is called for: All of the text down to the \.{@y} is supposed to match. An error message is issued if any discrepancy is found. Then the procedure prepares to read the next line from \\{change\_file}. \Y\P\4\X6:Functions\X${}+\S{}$\6 $\\{check\_change}(\,)$\5 \C{ switches to \\{change\_file} if the buffers match }\6 $\{$\1\6 \&{int} \|n$=\O{0};$\5 \C{ the number of discrepancies found }\7 \&{if} (\\{lines\_dont\_match})\1\5 \&{return};\2\6 \&{while} $(\O{1})$\5 $\{$\1\6 $\\{changing}=\O{1};$\5 $\\{print\_where}=\O{1};$\5 $\\{change\_line}\PP;$\6 \&{if} $(\R\\{input\_ln}(\\{change\_file}))$\5 $\{$\1\6 $\\{err\_print}(\.{"!\ Change\ file\ ended\ before\ @y"});$\5 $\\{change\_limit}=\O{0};$\5 $\\{changing}=\O{0};$\5 $\\{print\_where}=\O{1};$\5 \&{return};\6 \4$\}$\2\6 \X16:Check for erroneous \.{@i}\X;\5 \X20:If the current line starts with \.{@y}, report any discrepancies and % \&{return}\X;\6 \X18:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change\_limit}% \X;\6 $\\{changing}=\O{0};$\5 $\\{print\_where}=\O{1};$\5 $\\{cur\_line}\PP;$\6 \&{while} $(\R\\{input\_ln}(\\{cur\_file}))$\5 $\{$\5 \C{ pop the stack or quit }\1\6 \&{if} $(\\{include\_depth}\S\O{0})$\5 $\{$\1\6 $\\{err\_print}(\.{"!\ WEB\ file\ ended\ during\ a\ change"});$\5 $\\{input\_has\_ended}=\O{1};$\5 \&{return};\6 \4$\}$\2\6 $\\{include\_depth}\MM;$\5 $\\{print\_where}=\O{1};$\5 $\\{cur\_line}\PP;$\6 \4$\}$\2\6 \&{if} (\\{lines\_dont\_match})\1\5 $\|n\PP;$\2\6 \4$\}$\2\6 \4$\}$\2\par \M20. \P\X20:If the current line starts with \.{@y}, report any discrepancies and \&{return}\X${}\S{}$\6 \&{if} $(\\{limit}>\\{buffer}+\O{1}\W\\{buffer}[\O{0}]\S\.{@'@'})$\5 $\{$\1\6 \X15:Lowercasify $\\{buffer}[\O{1}]$\X;\6 \&{if} $(\\{buffer}[\O{1}]\S\.{@'x'}\V\\{buffer}[\O{1}]\S\.{@'z'})$\5 $\{$\1\6 $\\{loc}=\\{buffer}+\O{2};$\5 $\\{err\_print}(\.{"!\ Where\ is\ the\ matching\ @y?"});$\6 \4$\}$\2\5 \&{else} \1\&{if} $(\\{buffer}[\O{1}]\S\.{@'y'})$\5 $\{$\1\6 \&{if} $(\|n>\O{0})$\5 $\{$\1\6 $\\{loc}=\\{buffer}+\O{2};$\5 $\\{err\_print}(\.{"!\ Hmm...\ some\ of\ the\ preceding\ lines\ failed\ to\ match"});$\6 \4$\}$\2\6 \&{return};\6 \4$\}$\2\2\6 \4$\}$\2\par \U section~19.\fi \vfil\eject \def\runninghead{APPENDIX D --- TRANSLATION BY {\tentt TANGLE}} \section Appendix D. Here's the portion of the \cee\ code generated by \.{TANGLE} that corresponds to Appendix~A. Notice that module~15 has been tangled into module~20, and modules~16, 18 and~20 have been tangled into module~19. \vskip6pt \begingroup \def\tt{\eighttt} \baselineskip9pt \verbatim /*:13*//*19:*/ #line 372 "common.web" check_change() int n= 0; if(lines_dont_match)return; while(1){ changing= 1;print_where= 1;change_line++; if(!input_ln(change_file)){ err_print("! Change file ended before @y"); change_limit= 0;changing= 0;print_where= 1; return; /*16:*/ #line 338 "common.web" if(buffer[1]==0151){ loc= buffer+2; err_print("! No includes allowed in change file"); /*:16*/ #line 385 "common.web" /*20:*/ #line 402 "common.web" if(limit>buffer+1&&buffer[0]==0100){ /*15:*/ #line 333 "common.web" if(buffer[1]>=0130&&buffer[1]<=0132||buffer[1]==0111)buffer[1]+= 0172-0132; /*:15*/ #line 404 "common.web" if(buffer[1]==0170||buffer[1]==0172){ loc= buffer+2;err_print("! Where is the matching @y?"); else if(buffer[1]==0171){ if(n>0){ loc= buffer+2; err_print("! Hmm... some of the preceding lines failed to match"); return; /*:20*/ #line 387 "common.web" /*18:*/ #line 357 "common.web" change_limit= change_buffer-buffer+limit; strncpy(change_buffer,buffer,limit-buffer+1); /*:18*/ #line 388 "common.web" changing= 0;print_where= 1;cur_line++; while(!input_ln(cur_file)){ if(include_depth==0){ err_print("! WEB file ended during a change"); input_has_ended= 1;return; include_depth--;print_where= 1;cur_line++; if(lines_dont_match)n++; /*:19*//*21:*/ ?endgroup \endgroup \vfill\eject \def\runninghead{APPENDIX E --- MACROS FOR FORMATTING} \section Appendix E: The \.{cwebmac.tex} file. This is the file that extends ``plain \TeX'' format in order to support the features needed by the output of \.{WEAVE}. \vskip6pt \begingroup \def\tt{\eighttt} \baselineskip9pt \let\?=? \def\printmacs{\input cwebmac} \verbatim ?printmacs ?endgroup \endgroup \vfill\eject \narrower \def\runninghead{APPENDIX F --- NOTES ON FORMATTING} \section Appendix F: How to use \.{WEB} macros. The macros in \.{webmac} make it possible to produce a variety of formats without editing the output of \.{WEAVE}, and the purpose of this appendix is to explain some of the possibilities. \def\point#1.{\yskip\indent#1.\quad\ignorespaces} \point 1. Three fonts have been declared in addition to the standard fonts of \.{PLAIN} format: You can say `\.{\{\\sc stuff\}}' to get {\sc STUFF} in small caps; and you can select the largish fonts \.{\\titlefont} and \.{\\ttitlefont} in the title of your document, where \.{\\ttitlefont} is a typewriter style of type. \point 2. When you mention an identifier in \TeX\ text, you normally call it `\.{|identifier|}'. But you can also say `\.{\\\\\{identifier\}}'. The output will look the same in both cases, but the second alternative doesn't put \\{identifier} into the index, since it bypasses \.{WEAVE}'s translation from \cee\ mode. \point 3. To get typewriter-like type, as when referring to `\.{WEB}', you can use the `\.{\\.}' macro (e.g., `\.{\\.\{WEB\}}'). In the argument to this macro you should insert an additional backslash before the symbols listed as `special string characters' in the index to \.{WEAVE}, i.e., before backslashes and dollar signs and the like. A `\.{\\\ }' here will result in the visible space symbol; to get an invisible space following a control sequence you can say `\.{\{\ \}}'. [The `\.{\\)}' macro is similar to the preceding one, but instead of putting the string in an hbox it prints it in as many lines as necessary, with a backslash at the end of all but the last lines. A space not preceded by a backslash is ignored by this macro.] \point 4. The three control sequences \.{\\pagewidth}, \.{\\pageheight}, and \.{\\fullpageheight} can be redefined in the limbo section at the beginning of your \.{WEB} file, to change the dimensions of each page. The standard settings $$\lpile{\.{\\pagewidth=6.5in}\cr \.{\\pageheight=8.7in}\cr \.{\\fullpageheight=9in}\cr}$$ were used to prepare the present report; \.{\\fullpageheight} is \.{\\pageheight} plus room for the additional heading and page numbers at the top of each page. If you change any of these quantities, you should call the macro \.{\\setpage} immediately after making the change. \point 5. The \.{\\pageshift} macro defines an amount by which right-hand pages (i.e., odd-numbered pages) are shifted right with respect to left-hand (even-numbered) ones. By adjusting this amount you may be able to get two-sided output in which the page numbers line up on opposite sides of each sheet. \point 6. The \.{\\title} macro will appear at the top of each page in small caps. \dots \point 7. The first page usually is number 1; if you want some other starting page, just set \.{\\pageno} to the desired number. \dots \point 8. The macro \.{\\iftitle} will suppress the header line if it is defined by `\.{\\titletrue}'. The normal value is \.{\\titlefalse} except for the table of contents; thus, the contents page is usually unnumbered. If your program is so long that the table of contents doesn't fit on a single page, or if you want a number to appear on the contents page, you should reset \.{\\pageno} when you begin the table of contents. Two macros are provided to give flexibility to the table of contents: \.{\\topofcontents} is invoked just before the contents info is read, and \.{\\botofcontents} is invoked just after. [Here's a typical definition:] $$\lpile{\.{\\def\\topofcontents\{\\null\\vfill}\cr \.{ { }\\titlefalse \% include headline on the contents page}\cr \.{ { }\\def\\rheader\{\\mainfont The \{\\tt WEAVE\}{ }processor\\hfil\}}\cr \.{ { }\\centerline\{\\titlefont The \{\\ttitlefont WEAVE\}{ }processor\}}\cr \.{ { }\\vskip 15pt \\centerline\{(Version 2.5)\}{ }\\vfill\}}\cr}$$ Redefining \.{\\rheader}, which is the headline for right-hand pages, suffices in this case to put the desired information at the top of the page. \point 9. Data for the table of contents is written to a file that is read after the indexes have been \TeX ed; there's one line of data for every starred module. [Here's what the file \.{CONTENTS.TEX} might look like: $$\lpile{\.{\\Z \{{ }Introduction\}\{1\}\{16\}}\cr \.{\\Z \{{ }The character set\}\{11\}\{19\}}\cr}$$ and so on.] The \.{\\topofcontents} macro could redefine \.{\\Z} so that the information appears in another format. \point 10. Sometimes it is necessary or desirable to divide the output of \.{WEAVE} into subfiles that can be processed separately. For example, the listing of \TeX\ runs to more than 500 pages, and that is enough to exceed the capacity of many printing devices and/or their software. When an extremely large job isn't cut into smaller pieces, the entire process might be spoiled by a single error of some sort, making it necessary to start everything over. Here's a safe way to break a woven file into three parts: Say the pieces are $\alpha$, $\beta$, and $\gamma$, where each piece begins with a starred module. All macros should be defined in the opening limbo section of $\alpha$, and copies of this \TeX\ code should be placed at the beginning of $\beta$ and of $\gamma$. In order to process the parts separately, we need to take care of two things: The starting page numbers of $\beta$ and $\gamma$ need to be set up properly, and the table of contents data from all three runs needs to be accumulated. The \.{webmac} macros include two control sequences \.{\\contentsfile} and \.{\\readcontents} that facilitate the necessary processing. We include `\.{\\def\\contentsfile\{CONT1\}}' in the limbo section of $\alpha$, and we include `\.{\\def\\contentsfile\{CONT2\}}' in the limbo section of $\beta$; this causes \TeX\ to write the contents data for $\alpha$ and $\beta$ into \.{CONT1.TEX} and \.{CONT2.TEX}. Now in $\gamma$ we say $$\.{\\def\\readcontents\{\\input CONT1 \\input CONT2 \\input CONTENTS\}};$$ this brings in the data from all three pieces, in the proper order. However, we still need to solve the page-numbering problem. One way to do it is to include the following in the limbo material for $\beta$: $$\lpile{\.{\\message\{Please type the last page number of part 1: \}}\cr \.{\\read-1to\\\\ \\pageno=\\\\ \\advance\\pageno by 1}\cr}$$ Then you simply provide the necessary data when \TeX\ requests it; a similar construction is used at the beginning of $\gamma$. This method can, of course, be used to divide a woven file into any number of pieces. \point 11. Sometimes it is nice to include things in the index that are typeset in a special way. For example, we might want to have an index entry for `\TeX'. \.{WEAVE} provides only two standard ways to typeset an index entry (unless the entry is an identifier or a reserved word): `\.{@\^}' gives roman type, and `\.{@.}' gives typewriter type. But if we try to typeset `\TeX' in roman type by saying, e.g., `\.{@\^\\TeX@>}', the backslash character gets in the way, and this entry wouldn't appear in the index with the T's. The solution is to use the `\.{@:}' feature, declaring a macro that simply removes a sort key as follows: $$\.{\\def\\9\#1\{\}}$$ Now you can say, e.g., `\.{@:TeX\}\{\\TeX@>}' in your \.{WEB} file; \.{WEAVE} puts it into the index alphabetically, based on the sort key, and produces the macro call `\.{\\9\{TeX\}\{\\TeX\}}' which will ensure that the sort key isn't printed. A similar idea can be used to insert hidden material into module names so that they are alphabetized in whatever way you might wish. Some people call these tricks ``special refinements''; others call them ``kludges''. \point 12. The control sequence \.{\\modno} is set to the number of the module being typeset. \point 13. If you want to list only the modules that have changed, together with the index, put the command `\.{\\let\\maybe=\\iffalse}' in the limbo section before the first module of your \.{WEB} file. It's customary to make this the first change in your change file. \endnarrower \vfill\end